Skip to content

Stabilize cloud sync with snapshot conflict overwrite, persistent offline queue, and optimistic concurrency#1124

Draft
Copilot wants to merge 4 commits into
mainfrom
copilot/fix-hyperbook-cloud-sync-issues
Draft

Stabilize cloud sync with snapshot conflict overwrite, persistent offline queue, and optimistic concurrency#1124
Copilot wants to merge 4 commits into
mainfrom
copilot/fix-hyperbook-cloud-sync-issues

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented May 15, 2026 •
edited
Loading

This PR hardens cloud synchronization so stale-state conflicts converge without reload loops, offline edits survive reload/crash, and concurrent writes are guarded with optional optimistic concurrency checks.

Changes Made

Client sync hardening (packages/markdown/assets/cloud.js)

  • Keeps snapshot-overwrite conflict resolution as the deterministic stale-state recovery path (no reload-based recovery loop).
  • Persists offlineQueue in localStorage and reloads it on startup.
  • Automatically flushes persisted offline queue when back online.
  • Tracks and stores stateChecksum from server responses for concurrency matching.
  • Sends concurrency preconditions on normal writes and uses forced overwrite only in explicit conflict-recovery paths.
  • Clears persisted sync metadata (offlineQueue, checksum, last event id) on auth reset/logout.

Cloud API optimistic concurrency (platforms/cloud/routes/store.js)

  • Adds optional request guards:
    • ifMatchLastEventId
    • ifMatchChecksum
    • forceOverwrite (explicit override path)
  • Returns stateChecksum in:
    • GET /api/store/:hyperbookId
    • POST /api/store/:hyperbookId/events
    • POST /api/store/:hyperbookId/snapshot
  • Returns 409 conflict when preconditions fail, including server sync head/checksum context.

Regression tests

  • Added packages/markdown/tests/cloudSync.test.js:
    • verifies conflict resolution path avoids reload loops,
    • verifies offline queue persistence and reconnect flush behavior.
  • Added platforms/cloud/tests/storeOptimisticConcurrency.test.js:
    • verifies checksum responses,
    • verifies stale revision/checksum conflicts,
    • verifies forced overwrite behavior.

Validation

  • Targeted markdown cloud sync tests pass.
  • Cloud platform tests pass, including new optimistic concurrency coverage.
  • Root test run passes after required package builds in dependency order.

@vercel
Copy link
Copy Markdown

vercel Bot commented May 15, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
hyperbook-4fwa Ready Ready Preview, Comment May 15, 2026 7:13am

@mikebarkmin
Copy link
Copy Markdown
Member

mikebarkmin commented May 15, 2026

@copilot Is there some to improve about the cloud sync?

Copy link
Copy Markdown
Contributor Author

Copilot AI commented May 15, 2026

@copilot Is there some to improve about the cloud sync?

Yes — a few meaningful improvements are still possible:

  1. Persist offlineQueue in IndexedDB/localStorage so queued writes survive tab close/crash.
  2. Add optional server-side optimistic concurrency (revision/checksum) to reduce last-writer-wins overwrites.
  3. Add targeted tests for conflict + offline-reconnect flows to assert “no reload loop” behavior.

If you want, I can implement (1) first as the next incremental hardening step.

Copilot AI requested a review from mikebarkmin May 15, 2026 06:35
@mikebarkmin
Copy link
Copy Markdown
Member

mikebarkmin commented May 15, 2026

@copilot do all three

Copy link
Copy Markdown
Contributor Author

Copilot AI commented May 15, 2026

@copilot do all three

Implemented all three in commits 03b6beb and cf48be2:

  • persisted offline queue across reload/crash and auto-flush on reconnect,
  • optional optimistic concurrency (ifMatchLastEventId / ifMatchChecksum, with forceOverwrite escape hatch),
  • targeted regression tests for conflict + offline-reconnect paths to verify no reload loop.

Copilot AI changed the title Stabilize cloud sync by resolving stale-state conflicts via snapshot overwrite (no reload loop) Stabilize cloud sync with snapshot conflict overwrite, persistent offline queue, and optimistic concurrency May 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mikebarkmin mikebarkmin Awaiting requested review from mikebarkmin

Assignees

@mikebarkmin mikebarkmin

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@mikebarkmin